Expose OpenAI prompt cache request options - #6832

RFC status

Implementation complete and tested. This PR is ready for review. It is framed as an RFC because feedback is requested on the public OpenAiSchema.CreateResponse / OpenAiLanguageModel.Config shape, not because implementation work remains.

Summary

Expose the following OpenAI Responses API request-level options through OpenAiLanguageModel.Config:

• safety_identifier
• prompt_cache_key
• legacy prompt_cache_retention (in_memory or 24h)
• GPT-5.6+ prompt_cache_options (mode and ttl)

The request builder already forwards schema-derived config, so the implementation is deliberately limited to the handwritten request schema, request/schema tests, and a patch changeset. Content-level prompt_cache_breakpoint is not included; that remains #6831.

Design decisions

• Keep request configuration in the handwritten OpenAiSchema.CreateResponse, which is the source for the high-level model config and client request type.
• Model prompt_cache_options.mode as optional implicit | explicit and ttl as optional 30m, matching current GPT-5.6 Responses request semantics and defaults.
• Retain the legacy pre-GPT-5.6 field separately as prompt_cache_retention: in_memory | 24h.
• Enforce the documented 64-character maximum for safety_identifier.
• Do not add model-name gating. The model type accepts custom strings, so compatibility remains an OpenAI API concern rather than a brittle client-side model registry.
• Leave @effect/ai-openai-compat unchanged: it uses a separate Chat Completions-compatible request surface and is not the Responses high-level config reported in this issue.

Generated vs handwritten schema

The checked-in generated OpenAI request schema already contains safety_identifier, prompt_cache_key, and prompt_cache_retention, but it does not contain the newer prompt_cache_options. Current official OpenAI Responses documentation and the official Node SDK do document prompt_cache_options for GPT-5.6+.

This PR does not hand-edit Generated.ts or add a speculative codegen patch. The generated client is not the source of OpenAiLanguageModel.Config; keeping this change in the handwritten Responses schema provides the requested high-level support without creating a broad generated diff. Generated parity can follow when the configured Stainless schema includes the field, or via a maintainer-preferred codegen patch.

Focused RFC questions

1. Should prompt_cache_options remain an inline nested schema, consistent with nearby request options, or be exported as a named public schema?
2. Should these high-level optional config fields also accept explicit null to mirror raw OpenAI SDK types, or remain optional non-null values consistent with the existing handwritten config style?
3. Is leaving Generated.ts unchanged preferable until the configured upstream schema catches up, or would maintainers prefer a targeted codegen patch now?

Verification

• pnpm lint-fix
• pnpm test --run packages/ai/openai/test/OpenAiLanguageModel.test.ts packages/ai/openai/test/OpenAiSchema.test.ts — 61 tests passed
• pnpm check
• Independent review loop completed; the final pass reported no actionable findings.

Positive tests verify that all supported fields survive high-level model config and reach real HTTP request bodies:

• non-streamed GPT-5.5 request: safety identifier, cache key, and legacy retention
• streamed GPT-5.6 request: safety identifier, cache key, cache options, and stream: true

Schema coverage also verifies the supported option shapes and rejects safety identifiers longer than 64 characters.

Tradeoffs

• The strict enums intentionally track current documented values; future OpenAI values will require a schema update.
• No client-side model compatibility check is added, avoiding false rejection of custom or newly released model identifiers.
• Generated and handwritten request schemas remain temporarily asymmetric for prompt_cache_options; that limitation is explicit rather than hidden by guessing at generated output.

Closes #6830